VS_Browse()          Database pick-list/browser routine                   CHG

Description:

  VS_Browse() allows the user to pick a database record from a "pick
  list/browse" window.  The window can contain as many field columns as
  you (the programmer) want to provide as the user may "pan" left and
  right (in addition to scrolling up and down) within the window.

Syntax:     

  n_Key = VS_Browse( n_Top, n_Left, n_Bottom, n_Right, c_Title,
  c_FootNote, n_Palette, a_ColObjs, c_FirstKey, b_Condition, ac_Procs,
  an_Keys )

Pass:       

  n_Top is a numeric value containing the top row of the window.

  n_Left is a numeric value containing the left column of the
  window.

  n_Bottom is a numeric value containing the bottom row of the
  window.

  n_Right is a numeric value containing the right column of the
  window.

  c_Title is a character expression that will be displayed at the
  top of the window (offset to the left)

  c_Footnote is a character expression that will be displayed at the
  bottom of the window (centered)

  n_Palette is a numeric value representing the palette number
  VS_Browse() will use when it creates the window.

  a_ColObjs is an array of TBColumn Objects.  Each element in this
  array represents one column in the window.  See Clipper v5.0x
  documentation under TBColumn for more information.

  c_FirstKey is an optional character expression that represents the
  index key of the first record to display.  i.e. If the database were
  indexed on last_name and c_FirstKey contained "SMITH", then the
  first record displayed in the window would have the last name of
  "SMITH".

  b_Condition is an optional code block that is evaluated for each
  record prior to its being displayed in the window.  This code block
  should return .T. only when the record in question is within the range
  of records you wish to see in the window.  i.e. using the "SMITH"
  example above... if you only wanted to see a list of persons with the
  last name of "SMITH", this code block code look like this:
  {|x|LAST_NAME==x}.

  ac_Procs is an optional array of character expressions that tell
  VS_Browse() which procedures to call within the window.

  an_Keys is an optional array of numeric values (parallel to
  ac_Procs) that indicate to VS_Browse() the INKEY() values of which
  keys invoke which procedure.  In other words, if the user presses a
  key listed in this array, VS_Browse() will call the procedure named in
  the parallel element of ac_Procs.

Return:     

  n_Key is a numeric expression that represents the INKEY() value of
  the last key the user pressed.


Notes:      

  VS_Browse() replaces VS_Pick().

Example:    

  LOCAL n_Key          := 0
  LOCAL n_Top          := 5
  LOCAL n_Left         := 5
  LOCAL n_Bottom       := 20
  LOCAL n_Right        := 75
  LOCAL c_Title        := " This is the title "
  LOCAL c_FootNote     := " This is the footnote "
  LOCAL n_Palette      := 5
  LOCAL a_ColObjs      := {}
  LOCAL c_FirstKey
  LOCAL b_Condition
  LOCAL ab_KeyBlocks
  LOCAL an_Keys

     VS_InitVern()

     USE VERNSIX INDEX VERNSIX

     AADD( a_ColObjs, TBColumnNew( "Function        - Short
  Description", ;
                                    {||FUNC_NAME+[ - ]+SHORT} ) )

     n_Key = VS_Browse(n_Top, n_Left, n_Bottom, n_Right, c_Title,
  c_FootNote,;
             n_Palette, a_ColObjs )

     ? "n_Key=",n_Key
     ? "RECNO()=",RECNO()

Usage:      

  VS_Browse() can be used anytime you want a user to be able to select a
  record from a database.  I find it to be a very valuable tool inside
  validation routines, etc.